home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / complib / cppsvx.z / cppsvx
Encoding:
Text File  |  1998-10-30  |  10.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CPPSVX - use the Cholesky factorization A = U**H*U or A = L*L**H to
  10.      compute the solution to a complex system of linear equations  A * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE CPPSVX( FACT, UPLO, N, NRHS, AP, AFP, EQUED, S, B, LDB, X,
  14.                         LDX, RCOND, FERR, BERR, WORK, RWORK, INFO )
  15.  
  16.          CHARACTER      EQUED, FACT, UPLO
  17.  
  18.          INTEGER        INFO, LDB, LDX, N, NRHS
  19.  
  20.          REAL           RCOND
  21.  
  22.          REAL           BERR( * ), FERR( * ), RWORK( * ), S( * )
  23.  
  24.          COMPLEX        AFP( * ), AP( * ), B( LDB, * ), WORK( * ), X( LDX, * )
  25.  
  26. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  27.      CPPSVX uses the Cholesky factorization A = U**H*U or A = L*L**H to
  28.      compute the solution to a complex system of linear equations
  29.         A * X = B, where A is an N-by-N Hermitian positive definite matrix
  30.      stored in packed format and X and B are N-by-NRHS matrices.
  31.  
  32.      Error bounds on the solution and a condition estimate are also provided.
  33.  
  34.  
  35. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  36.      The following steps are performed:
  37.  
  38.      1. If FACT = 'E', real scaling factors are computed to equilibrate
  39.         the system:
  40.            diag(S) * A * diag(S) * inv(diag(S)) * X = diag(S) * B
  41.         Whether or not the system will be equilibrated depends on the
  42.         scaling of the matrix A, but if equilibration is used, A is
  43.         overwritten by diag(S)*A*diag(S) and B by diag(S)*B.
  44.  
  45.      2. If FACT = 'N' or 'E', the Cholesky decomposition is used to
  46.         factor the matrix A (after equilibration if FACT = 'E') as
  47.            A = U'* U ,  if UPLO = 'U', or
  48.            A = L * L',  if UPLO = 'L',
  49.         where U is an upper triangular matrix, L is a lower triangular
  50.         matrix, and ' indicates conjugate transpose.
  51.  
  52.      3. The factored form of A is used to estimate the condition number
  53.         of the matrix A.  If the reciprocal of the condition number is
  54.         less than machine precision, steps 4-6 are skipped.
  55.  
  56.      4. The system of equations is solved for X using the factored form
  57.         of A.
  58.  
  59.      5. Iterative refinement is applied to improve the computed solution
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  71.  
  72.  
  73.  
  74.         matrix and calculate error bounds and backward error estimates
  75.         for it.
  76.  
  77.      6. If equilibration was used, the matrix X is premultiplied by
  78.         diag(S) so that it solves the original system before
  79.         equilibration.
  80.  
  81.  
  82. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  83.      FACT    (input) CHARACTER*1
  84.              Specifies whether or not the factored form of the matrix A is
  85.              supplied on entry, and if not, whether the matrix A should be
  86.              equilibrated before it is factored.  = 'F':  On entry, AFP
  87.              contains the factored form of A.  If EQUED = 'Y', the matrix A
  88.              has been equilibrated with scaling factors given by S.  AP and
  89.              AFP will not be modified.  = 'N':  The matrix A will be copied to
  90.              AFP and factored.
  91.              = 'E':  The matrix A will be equilibrated if necessary, then
  92.              copied to AFP and factored.
  93.  
  94.      UPLO    (input) CHARACTER*1
  95.              = 'U':  Upper triangle of A is stored;
  96.              = 'L':  Lower triangle of A is stored.
  97.  
  98.      N       (input) INTEGER
  99.              The number of linear equations, i.e., the order of the matrix A.
  100.              N >= 0.
  101.  
  102.      NRHS    (input) INTEGER
  103.              The number of right hand sides, i.e., the number of columns of
  104.              the matrices B and X.  NRHS >= 0.
  105.  
  106.      AP      (input/output) COMPLEX array, dimension (N*(N+1)/2)
  107.              On entry, the upper or lower triangle of the Hermitian matrix A,
  108.              packed columnwise in a linear array, except if FACT = 'F' and
  109.              EQUED = 'Y', then A must contain the equilibrated matrix
  110.              diag(S)*A*diag(S).  The j-th column of A is stored in the array
  111.              AP as follows:  if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for
  112.              1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for
  113.              j<=i<=n.  See below for further details.  A is not modified if
  114.              FACT = 'F' or 'N', or if FACT = 'E' and EQUED = 'N' on exit.
  115.  
  116.              On exit, if FACT = 'E' and EQUED = 'Y', A is overwritten by
  117.              diag(S)*A*diag(S).
  118.  
  119.      AFP     (input or output) COMPLEX array, dimension (N*(N+1)/2)
  120.              If FACT = 'F', then AFP is an input argument and on entry
  121.              contains the triangular factor U or L from the Cholesky
  122.              factorization A = U**H*U or A = L*L**H, in the same storage
  123.              format as A.  If EQUED .ne. 'N', then AFP is the factored form of
  124.              the equilibrated matrix A.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  137.  
  138.  
  139.  
  140.              If FACT = 'N', then AFP is an output argument and on exit returns
  141.              the triangular factor U or L from the Cholesky factorization A =
  142.              U**H*U or A = L*L**H of the original matrix A.
  143.  
  144.              If FACT = 'E', then AFP is an output argument and on exit returns
  145.              the triangular factor U or L from the Cholesky factorization A =
  146.              U**H*U or A = L*L**H of the equilibrated matrix A (see the
  147.              description of AP for the form of the equilibrated matrix).
  148.  
  149.      EQUED   (input or output) CHARACTER*1
  150.              Specifies the form of equilibration that was done.  = 'N':  No
  151.              equilibration (always true if FACT = 'N').
  152.              = 'Y':  Equilibration was done, i.e., A has been replaced by
  153.              diag(S) * A * diag(S).  EQUED is an input argument if FACT = 'F';
  154.              otherwise, it is an output argument.
  155.  
  156.      S       (input or output) REAL array, dimension (N)
  157.              The scale factors for A; not accessed if EQUED = 'N'.  S is an
  158.              input argument if FACT = 'F'; otherwise, S is an output argument.
  159.              If FACT = 'F' and EQUED = 'Y', each element of S must be
  160.              positive.
  161.  
  162.      B       (input/output) COMPLEX array, dimension (LDB,NRHS)
  163.              On entry, the N-by-NRHS right hand side matrix B.  On exit, if
  164.              EQUED = 'N', B is not modified; if EQUED = 'Y', B is overwritten
  165.              by diag(S) * B.
  166.  
  167.      LDB     (input) INTEGER
  168.              The leading dimension of the array B.  LDB >= max(1,N).
  169.  
  170.      X       (output) COMPLEX array, dimension (LDX,NRHS)
  171.              If INFO = 0, the N-by-NRHS solution matrix X to the original
  172.              system of equations.  Note that if EQUED = 'Y', A and B are
  173.              modified on exit, and the solution to the equilibrated system is
  174.              inv(diag(S))*X.
  175.  
  176.      LDX     (input) INTEGER
  177.              The leading dimension of the array X.  LDX >= max(1,N).
  178.  
  179.      RCOND   (output) REAL
  180.              The estimate of the reciprocal condition number of the matrix A
  181.              after equilibration (if done).  If RCOND is less than the machine
  182.              precision (in particular, if RCOND = 0), the matrix is singular
  183.              to working precision.  This condition is indicated by a return
  184.              code of INFO > 0, and the solution and error bounds are not
  185.              computed.
  186.  
  187.      FERR    (output) REAL array, dimension (NRHS)
  188.              The estimated forward error bound for each solution vector X(j)
  189.              (the j-th column of the solution matrix X).  If XTRUE is the true
  190.              solution corresponding to X(j), FERR(j) is an estimated upper
  191.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          CCCCPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  203.  
  204.  
  205.  
  206.              divided by the magnitude of the largest element in X(j).  The
  207.              estimate is as reliable as the estimate for RCOND, and is almost
  208.              always a slight overestimate of the true error.
  209.  
  210.      BERR    (output) REAL array, dimension (NRHS)
  211.              The componentwise relative backward error of each solution vector
  212.              X(j) (i.e., the smallest relative change in any element of A or B
  213.              that makes X(j) an exact solution).
  214.  
  215.      WORK    (workspace) COMPLEX array, dimension (2*N)
  216.  
  217.      RWORK   (workspace) REAL array, dimension (N)
  218.  
  219.      INFO    (output) INTEGER
  220.              = 0:  successful exit
  221.              < 0:  if INFO = -i, the i-th argument had an illegal value
  222.              > 0:  if INFO = i, and i is
  223.              <= N: the leading minor of order i of A is not positive definite,
  224.              so the factorization could not be completed, and the solution and
  225.              error bounds could not be computed.  = N+1: RCOND is less than
  226.              machine precision.  The factorization has been completed, but the
  227.              matrix is singular to working precision, and the solution and
  228.              error bounds have not been computed.
  229.  
  230. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  231.      The packed storage scheme is illustrated by the following example when N
  232.      = 4, UPLO = 'U':
  233.  
  234.      Two-dimensional storage of the Hermitian matrix A:
  235.  
  236.         a11 a12 a13 a14
  237.             a22 a23 a24
  238.                 a33 a34     (aij = conjg(aji))
  239.                     a44
  240.  
  241.      Packed storage of the upper triangle of A:
  242.  
  243.      AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.